package com.zds.zds_picture_backend.service;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.zds.zds_picture_backend.api.aliyunai.model.CreateOutPaintingTaskResponse;
import com.zds.zds_picture_backend.model.dto.picture.*;
import com.zds.zds_picture_backend.model.entity.Picture;
import com.zds.zds_picture_backend.model.entity.User;
import com.zds.zds_picture_backend.model.vo.PictureVO;
import org.springframework.scheduling.annotation.Async;

import javax.servlet.http.HttpServletRequest;
import java.util.List;

/**
 * @author 33882
 * @description 针对表【picture(图片)】的数据库操作Service接口，定义图片相关的业务操作方法
 * @createDate 2025-10-02 15:57:58
 */
public interface PictureService extends IService<Picture> {

    /**
     * 上传图片（支持新增或更新图片信息）
     *
     * @param inputSource         图片源（可以是文件对象或URL字符串）
     * @param pictureUploadRequest 图片上传请求参数（包含图片名称、所属空间等信息）
     * @param loginUser           当前登录用户（用于权限校验和关联用户信息）
     * @return 上传成功后的图片视图对象（PictureVO），包含图片的详细信息
     */
    PictureVO uploadPicture(Object inputSource, PictureUploadRequest pictureUploadRequest, User loginUser);

    /**
     * 构建图片查询条件封装器
     *
     * @param pictureQueryRequest 图片查询请求参数（包含各种查询条件，如名称、分类、空间ID等）
     * @return 构建好的QueryWrapper对象，用于MyBatis-Plus的查询操作
     */
    QueryWrapper<Picture> getQueryWrapper(PictureQueryRequest pictureQueryRequest);

    /**
     * 分页获取图片的视图对象列表（包含关联的用户信息）
     *
     * @param picturePage 图片实体的分页对象（从数据库查询得到）
     * @param request     HTTP请求对象（可用于获取上下文信息）
     * @return 包含图片视图对象（PictureVO）的分页对象，每个VO包含图片详情及关联用户信息
     */
    Page<PictureVO> getPictureVOPage(Page<Picture> picturePage, HttpServletRequest request);

    /**
     * 将图片实体对象转换为视图对象（包含关联用户信息）
     *
     * @param picture 图片实体对象（数据库查询结果）
     * @param request HTTP请求对象（可用于获取上下文信息）
     * @return 图片视图对象（PictureVO），包含图片详情及关联用户信息
     */
    PictureVO getPictureVO(Picture picture, HttpServletRequest request);

    /**
     * 校验图片实体参数的合法性（如字段长度、非空校验等）
     *
     * @param picture 需要校验的图片实体对象
     */
    void validPicture(Picture picture);

    /**
     * 处理图片审核操作（设置审核状态、审核人、审核信息等）
     *
     * @param pictureReviewRequest 图片审核请求参数（包含图片ID、审核状态、审核意见等）
     * @param loginUser            当前登录用户（审核人，需具备审核权限）
     */
    void doPictureReview(PictureReviewRequest pictureReviewRequest, User loginUser);

    /**
     * 填充图片的审核相关参数（根据用户角色自动设置审核状态，如管理员上传的图片自动通过审核）
     *
     * @param picture   图片实体对象（待设置审核参数）
     * @param loginUser 当前登录用户（上传者，用于判断角色）
     */
    void fillReviewParams(Picture picture, User loginUser);

    /**
     * 批量上传图片（从指定来源抓取图片并批量上传）
     *
     * @param pictureUploadByBatchRequest 批量上传请求参数（包含搜索关键词、上传数量、名称前缀等）
     * @param loginuser                   当前登录用户（用于权限校验和关联用户信息）
     * @return 成功上传的图片数量
     */
    Integer uploadPictureByBatch(PictureUploadByBatchRequest pictureUploadByBatchRequest,
                                 User loginuser);

    /**
     * 异步清理图片文件（当图片记录被删除且无其他引用时，删除存储中的图片文件）
     *
     * @param oldPicture 被删除的图片实体对象（包含图片存储路径等信息）
     */
    @Async
    void clearPictureFile(Picture oldPicture);

    //以及被校验权限所替代
//    /**
//     * 检查用户对图片的操作权限（如是否为图片所有者、是否为空间管理员等）
//     *
//     * @param user    当前登录用户
//     * @param picture 待操作的图片实体对象
//     */
//    void checkPictureAuth(User user, Picture picture);

    /**
     * 删除图片（从数据库删除记录，并更新所属空间的额度，异步清理图片文件）
     *
     * @param pictureId 要删除的图片ID
     * @param loginUser 当前登录用户（用于权限校验）
     */
    void deletePicture(long pictureId, User loginUser);

    /**
     * 编辑图片信息（如更新名称、分类、标签等）
     *
     * @param pictureEditRequest 图片编辑请求参数（包含待更新的图片ID及字段信息）
     * @param loginUser          当前登录用户（用于权限校验）
     */
    void editPicture(PictureEditRequest pictureEditRequest, User loginUser);

    /**
     * 根据颜色搜索图片（在指定空间内，按颜色相似度排序返回图片）
     *
     * @param spaceId   图片所属空间ID
     * @param picColor  目标颜色（十六进制字符串，如#FFFFFF）
     * @param loginuser 当前登录用户（用于权限校验）
     * @return 按颜色相似度排序的图片视图对象列表
     */
    List<PictureVO> searchPictureByColor(Long spaceId, String picColor, User loginuser);

    /**
     * 批量编辑图片（批量更新指定图片的分类和标签）
     *
     * @param pictureEditByBatchRequest 批量编辑请求参数（包含待编辑的图片ID列表、新分类、新标签等）
     * @param loginUser                 当前登录用户（用于权限校验）
     */
    void editPictureByBatch(PictureEditByBatchRequest pictureEditByBatchRequest, User loginUser);

    /**
     * 阔图
     *
     * @param createPictureOutPaintingTaskRequest
     * @param loginUser
     */
    public CreateOutPaintingTaskResponse createPictureOutPaintingTask(CreatePictureOutPaintingTaskRequest createPictureOutPaintingTaskRequest, User loginUser);
}